/*
 * Created on 2-Jul-06 Filename: IOTarget.java @author Daniel Yule
 */
package com.danicsoft.daide.command;

import com.danicsoft.daide.token.TokenGroup;

/**
 * Any class that implements this interface must be capable of reading from and
 * writing to a <code>TokenGroup</code>. This is a rather tricky operation
 * and should probably only be attempted by me (Daniel). For more details
 * however, consult {@link TokenIO}.
 * 
 * @author Daniel Yule (daniel.yule@gmail.com)
 * @version 1.0
 * @see TokenIO
 */
public interface IOTarget {

	/**
	 * Do either input or output on this object. In general, if we are doing
	 * input, we are reading the <code>TokenGroup</code> and assigning
	 * variables in the <code>IOTarget</code>. If we are doing output, we are
	 * adding to the <code>TokenGroup</code> from the members of the
	 * <code>IOTarget</code>. This is not to say that we must do something
	 * different if we are doing input or output, the whole point is that it is
	 * the same set of calls either way.
	 * 
	 * @param tokenIO
	 *        A subclass of <code>TokenIO</code> which does either input or
	 *        output.
	 * @param tokens
	 *        A <code>TokenGroup</code> we are either reading from or writing
	 *        to.
	 * @throws ParseException
	 *         If a problem was encountered while reading the tokens. (Very
	 *         rarely thrown when outputting).
	 */
	public void doIO(TokenIO tokenIO, TokenGroup tokens) throws ParseException;

	/**
	 * <p>
	 * Create a new instance of this IOTarget. This is typically just a call to
	 * the object's constructor. It exists so that a whole pile of new objects
	 * can be created from one original object (For example, a list creates a
	 * new instance and then does the IO required on this instance before adding
	 * it to the list.)
	 * </p>
	 * <p>
	 * Note that this could be accomplished via reflection except in the case of
	 * non-static inner classes (of which I make intensive use) which require
	 * knowledge of their enclosing object, which cannot be determined at
	 * runtime, as far as I know.
	 * </p>
	 * 
	 * @return A new instance of this class.
	 */
	public IOTarget newInstance();
}
